home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Games Collection 1 / software vault.zip / software vault / CDR10 / XLIB06.ZIP / XLIBREF1.DOC < prev    next >
Text File  |  1993-10-06  |  60KB  |  1,656 lines
  1. PART 1 of 2
  2. -----------------------------------------------------------------------------
  3.  
  4.   *********      XLIB - Mode X graphics library           ****************
  5.   *********                                               ****************
  6.   ********* Written By Themie Gouthas                     ****************
  7.   *********                                               ****************
  8.   ********* egg@dstos3.dsto.gov.au                        ****************
  9.   ********* teg@bart.dsto.gov.au                          ****************
  10.  
  11.       Some of the code in this library has been contributed by :
  12.  
  13.                Matthew MacKenzie - matm@eng.umd.edu
  14.  
  15.                 and others. See individual modules.
  16.  
  17.          I informally reserve all rights to the code in XLIB
  18.      Rights to contributed code is also assumed to be reserved by
  19.                    the original authors.
  20. -----------------------------------------------------------------------------
  21.  
  22. DISCLAIMER
  23.  
  24.  This library is distributed AS IS. The author/s specifically disclaim
  25.  any responsibility for any loss of profit or any incidental, consequen-
  26.  tial or other damages.
  27.  
  28. ---------------------------------------------------------------------------
  29. INTRODUCTION
  30. ---------------------------------------------------------------------------
  31.  
  32. XLIB is a "user supported freeware" graphics library specifically designed
  33. with game programming in mind.
  34.  
  35. It has been placed in the public domain for the benefit of all, and
  36. represents *MANY* hours of work so it is requested that all users comply
  37. with the the wishes of the author/s as specified in the individual modules
  38. and:
  39. a) To leave the code in the public domain
  40. b) Not distribute any modified or incomplete versions of this library
  41.  
  42. New contribution and comments are welcome and hopefully there will be
  43. more releases as the code evolves.
  44.  
  45. Finally, do not trust this excuse for a manual if in doubt, as this code has
  46. undergone several revisions. The place to get the answers is in the code
  47. itself.
  48.  
  49. REQUIREMENTS
  50.  
  51. Minimum requirements
  52.         286 processor,
  53.     Turbo C 2.0 or higher, or BORLANDC
  54.     MAKE  2.0 or higher
  55.     TLIB  2.0 or higher
  56.     Turbo Assembler 1.01 or higher
  57.  
  58.  
  59. GENERAL FEATURES
  60.  
  61.    Support for a number of 256 colour tweaked graphics mode resolutions
  62.    320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480
  63.    360x360 376x308 376x564
  64.  
  65.    Please note that some of the new resolutions best suit monitors with
  66.    adjustable vertical height.
  67.  
  68.    Virtual screens larger than the physical screen (memory
  69.    permitting) that can be panned at pixel resolution in all directions
  70.  
  71.    A split screen capability for status displays etc.
  72.  
  73.    Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts
  74.  
  75.    Support for page flipping
  76.  
  77.    Graphics primitives such as line and rectangle drawing functions and
  78.    of course bit block manipulation functions
  79.  
  80. MODULES COMPRISING XLIB
  81.    XMAIN    - Main module containig mode setting code and basic functions
  82.    XPOINT   - Pixel functions
  83.    XRECT    - Filled Rectangle and VRAM to VRAM block move functions
  84.    XPAL     - Palette functions
  85.    XLINE    - Line Functions
  86.    XTEXT    - Text and Font Functions
  87.    XPRINTF  - Printf style string output
  88.    XPBITMAP - Planar Bitmap functions
  89.    XCBITMAP - Compiled Bitmap functions
  90.    XVBITMAP - Video Bitmap functions
  91.    XPBMCLIP - Clipped Planar Bitmap functions
  92.    XMAKEVBM - Support module for video bitmaps
  93.    XBMTOOLS - Bitmap format conversion tools
  94.    XDETECT  - Hardware detection module
  95.    XFILEIO  - File I/O functions
  96.    XRLETOOL - RLE encoding/decoding functions
  97.    XMOUSE   - Mouse functions
  98.    XBEZIER  - Bezier curve drawing
  99.  
  100. -------------------------------------------------------------------------
  101. BUILDING THE LIBRARIES
  102. -------------------------------------------------------------------------
  103.  
  104. Building the library had been made simple through the use of make.
  105.  
  106. To build and examples for one of the two models:
  107.  
  108. a) edit the makefile for the apropriate model (see note in the makefile)
  109. b) edit the makefile for the apropriate compiler (again see note in the
  110.    makefile)
  111. c) type "make" at the dos prompt.
  112.  
  113. It should be as simple as that. If problems are encountered then check
  114. to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.
  115. If not either change your path or specify the full path for these programs
  116. in the makefile. It is preferrable to have your path set correctly.
  117.  
  118. Individual Compilation
  119. ----------------------
  120.  
  121. each ASM module can be compiled with the following commandline:
  122.  
  123. tasm /ml /d<model> <asm module name>
  124.  
  125. where <model> is s c or l. Where s = small model, c = compact model and
  126. l = large model.
  127.  
  128. The resulting libraries are:
  129.  
  130.   xlib<version>s.lib    - small model library
  131.   xlib<version>c.lib    - large model library
  132.   xlib<version>l.lib    - large model library
  133.  
  134. To link the library with your programs just include the apropriate .lib
  135. file in your project file or on the BCC or TCC command line.
  136.  
  137. Using the library with your programs
  138. ------------------------------------
  139.  
  140. Using the XLIB library in your programs is simple. Knowing the particular
  141. modules you require, just include the associated header files in your program
  142. and link your program modules with the library. If you don't want to wory
  143. about selecting the apropriate header file then just include "XLIB_ALL.H"
  144. which automatically includes all XLIB header files in your program.
  145.  
  146. For example compilations see the supplied makefile.
  147.  
  148. --------------------------------------------------------------------------
  149. GLOBAL DEFINES (xlib.inc)
  150. --------------------------------------------------------------------------
  151.  
  152. Types
  153.  
  154.  BYTE unsigned char
  155.  WORD unsigned int
  156.  
  157. Available X mode resolutions
  158.  
  159.  X_MODE_320x200  0
  160.  X_MODE_320x240  1
  161.  X_MODE_360x200  2
  162.  X_MODE_360x240  3
  163.  X_MODE_360x282  4
  164.  X_MODE_320x400  5
  165.  X_MODE_320x480  6
  166.  X_MODE_360x400  7
  167.  X_MODE_360x480  8
  168.  X_MODE_360x360  9
  169.  X_MODE_376x308  10
  170.  X_MODE_376x564  11
  171.  
  172. Palette rotation direction directiion
  173.  
  174.  BACKWARD 0
  175.  FORWARD  1
  176.  
  177.  
  178.  X_MODE_INVALID -1
  179.  ERROR           1
  180.  OK              0
  181.  
  182.  
  183. --------------------------------------------------------------------------
  184. MODULE XMAIN
  185. --------------------------------------------------------------------------
  186.  
  187. The Xmain module is the base module of the XLIB library. It contains the
  188. essential functions that initialize and customize the graphic environment.
  189.  
  190.  
  191. ASM SOURCES
  192.  
  193.    xmain.asm xmain.inc xlib.inc model.inc
  194.  
  195. C HEADER FILE
  196.  
  197.    xlib.h
  198.  
  199. EXPORTED VARIABLES
  200.  
  201.   NOTE: All variables are read only unless otherwise specified. If you modify
  202.   them manually, the results may be unpredictable.
  203.  
  204.   InGraphics -  BYTE -  Flag indicating that the xlib graphics system is
  205.        active. Set by function "x_set_mode".
  206.  
  207.   CurrXMode - WORD - If the xlib graphics system is active, contains the id
  208.        of the x mode. Set by function "x_set_mode".
  209.        See also defines (ie X_MODE_320x200 ... )
  210.  
  211.   ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by
  212.        function "x_set_mode"
  213.  
  214.   ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by
  215.        function "x_set_mode"
  216.  
  217.   ScrnPhysicalHeight - WORD - Physical screen height in pixels. Set by
  218.        function "x_set_mode".
  219.  
  220.   ErrorValue - WORD - Contains error value. General use variable to
  221.        communicate the error status from several functions. The value
  222.        in this variable usually is only valid for the the last
  223.        function called that sets it.
  224.  
  225.   SplitScrnOffs - WORD - Offset in video ram of split screen. Set by
  226.        function "x_set_splitscrn". The value is only valid if a split
  227.        screen is active. See also global variable "SplitScrnActive".
  228.  
  229.   SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at
  230.        initially when set by function "x_set_splitscrn". The value is only
  231.        valid if a split screen is active. See also global variable
  232.        "SplitScrnActive".This variable is not updated by "x_hide_splitscrn",
  233.        "x_adjust_splitscrn".
  234.  
  235.   SplitScrnVisibleHeight - WORD - The number of rows of the initial split
  236.        screen which are currently displayed. Modified by "x_hide_splitscrn",
  237.        "x_adjust_splitscrn" and "x_show_splitscrn".
  238.  
  239.   Page0_Offs - WORD - Offset in video ram of main virtual screen. Initially
  240.        set by function "x_set_mode" but is updated by functions
  241.        "x_set_splitscrn" and "x_set_doublebuffer".
  242.  
  243.   Page1_Offs - WORD - Offset in video ram of second virtual screen. Set by
  244.        and only is valid after a call to "x_set_doublebuffer".
  245.  
  246.   ScrnLogicalByteWidth - WORD - Virtual screen width in bytes. Set by
  247.        function "x_set_mode".
  248.  
  249.   ScrnLogicalPixelWidth - WORD - Virtual screen width in pixels. Set
  250.        by function "x_set_mode".
  251.  
  252.   ScrnLogicalHeight - WORD - Virtual screen height in pixels. Set
  253.        initially by function "x_set_mode" but is updated by functions
  254.        "x_set_splitscrn" and "x_set_doublebuffer".
  255.  
  256.   MaxScrollX - WORD - Max X pixel position of physical screen within
  257.        virtual screen. Set by function "x_set_mode".
  258.  
  259.   MaxScrollY - WORD - Max Y position of physical screen within virtual
  260.        screen. Set initially by function "x_set_mode" but is updated by
  261.        functions "x_set_splitscrn" and "x_set_doublebuffer".
  262.  
  263.   DoubleBufferActive - WORD - Indicates whether double-buffering is on. Set
  264.        by function "x_set_doublebuffer".
  265.  
  266.   VisiblePageIdx - WORD - Index number of current visible page. Initially
  267.        set by function "x_set_doublebuffer" but is updated by "x_page_flip".
  268.        This variable is only used while double buffering is on.
  269.  
  270.   HiddenPageOffs - WORD - Offset of hidden page. Initially set by function
  271.        "x_set_doublebuffer" but is updated by "x_page_flip". This variable
  272.        is only used while double buffering is on.
  273.  
  274.   VisiblePageOffs - WORD - Offset of visible page. Initially set by function
  275.        "x_set_doublebuffer" but is updated by "x_page_flip". This variable
  276.        is only used while double buffering is on.
  277.  
  278.   NonVisual_Offs - WORD - Offset of first byte of non-visual ram, the ram
  279.        that is available for bitmap storage etc. Set initially by function
  280.        "x_set_mode" but is updated by functions "x_set_splitscrn" and
  281.        "x_set_doublebuffer".
  282.  
  283.   TopClip, BottomClip, LeftClip RightClip - WORD - Define the clipping
  284.        rectangle for Linear and Video clipped bitmap put functions. Set
  285.        either manually or by "x_set_cliprect". Note X coordinates are in
  286.        bytes as all clip functions clip to byte boundaries.
  287.  
  288.   PhysicalStartPixelX - WORD - X pixel Offset of physical (visible) screen
  289.        relative to the upper left hand corner (0,0) of the virtual screen.
  290.  
  291.   PhysicalStartByteX - WORD - X byte Offset of physical (visible) screen
  292.        relative to the upper left hand corner (0,0) of the virtual screen.
  293.  
  294.   PhysicalStartY - WORD - Y pixel Offset of physical (visible) screen
  295.        relative to the upper left hand corner (0,0) of the virtual screen.
  296.  
  297. EXPORTED FUNCTIONS
  298.  
  299.   x_set_mode
  300.   ----------
  301.     C Prototype:  extern WORD x_set_mode(WORD mode,WORD WidthInPixels);
  302.  
  303.      mode          - The required mode as defined by the "Available X Mode
  304.                      resolutions" set of defines in the xlib.h header file.
  305.      WidthInPixels - The required virtual screen width.
  306.      Returns       - The actual width in pixels of the allocated virtual
  307.                      screen
  308.  
  309.   This function initialises the graphics system, setting the apropriate
  310.   screen resolution and allocating a virtual screen. The virtual screen
  311.   allocated may not necessarily be of the same size as specified in the
  312.   "WidthInPixels" parameter as it is rounded down to the nearest
  313.   multiple of 4.
  314.  
  315.   The function returns the actual width of the allocated virtual screen
  316.   in pixels if a valid mode was selected otherwise returns
  317.   X_MODE_INVALID.
  318.  
  319.   Saves virtual screen pixel width in "ScrnLogicalPixelWidth".
  320.   Saves virtual screen byte  width in "ScrnLogicalByteWidth".
  321.   Physical screen dimensions are set in "ScrnPhysicalPixelWidth".
  322.   "ScrnPhysicalByteWidth" and "ScrnPhysicalHeight". Other global
  323.   variables set are "CurrXMode","MaxScrollX", "MaxScrollY",
  324.   "InGraphics". The variable "SplitScrnScanline" is also initialized
  325.   to zero.
  326.  
  327.   See also:
  328.      Available X Mode resolutions
  329.      What is Mode X
  330.  
  331.   x_select_default_plane
  332.   ----------------------
  333.  
  334.     C Prototype:  void x_select_default_plane(BYTE plane);
  335.  
  336.     Enables default Read/Write access to a specified plane
  337.  
  338.  
  339.   x_set_splitscreen
  340.   -----------------
  341.  
  342.     C Prototype:  extern void x_set_splitscreen(WORD line);
  343.  
  344.     line - The starting scan line of the required split screen.
  345.  
  346.   This function activates Mode X split screen and sets starting scan
  347.   line. The split screen resides on the bottom half of the screen and has
  348.   a starting address of A000:0000 in video RAM.
  349.  
  350.   It also Updates Page0_Offs to reflect the existence of the split screen
  351.   region ie "MainScrnOffset" is set to the offset of the first pixel
  352.   beyond the split screen region. Other variable set are "Page1_Offs" which
  353.   is set to the same value as "Page0_Offs" (see graphics call sequence
  354.   below), "ScrnLogicalHeight","ScrnPhysicalHeight", "SplitScrnScanLine" and
  355.   "MaxScrollY".
  356.  
  357.   This function cannot be called after double buffering has been activated,
  358.   it will return an error. To configure your graphics environment the
  359.   sequence of graphics calls is as follows although either or both steps b
  360.   and c may be omitted:
  361.     a) x_set_mode
  362.     b) x_set_splitscreen
  363.     c) x_set_doublebuffer
  364.   Thus when you call this function successfully, double buffering is not
  365.   active so "Page1_Offs" is set to the same address as "Page0_Offs".
  366.  
  367.   WARNING: If you use one of the high resolution modes (376x564 as an
  368.     extreme example) you may not have enough video ram for split screen
  369.     and double buffering options since VGA video RAM is restricted to
  370.     64K.
  371.  
  372.   See Also:
  373.     What is a Split Screen ?
  374.     What is double buffering ?
  375.  
  376.   x_set_doublebuffer
  377.   ------------------
  378.  
  379.   C Prototype: extern WORD x_set_doublebuffer(WORD PageHeight);
  380.  
  381.   PageHeight - The height of the two double buffering virtual screens.
  382.   Returns    - The closest possible height to the specified.
  383.  
  384.   This function sets up two double buffering virtual pages. 'ErrorValue"
  385.   is set according to the success or failure of this command.
  386.  
  387.   Other variables set are:
  388.  
  389.     _Page1_Offs                 Offset of second virtual page
  390.     _NonVisual_Offs          Offset of first non visible video ram byte
  391.     _DoubleBufferActive      Flag
  392.     _PageAddrTable           Table of Double buffering pages start offsets
  393.     _ScrnLogicalHeight       Logical height of the double buffering pages
  394.     _MaxScrollY              Max vertical start address of physical screen
  395.                              within the virtual screen
  396.  
  397.   WARNING: If you use one of the high resolution modes (376x564 as an
  398.     extreme example) you may not have enough video ram for split screen
  399.     and double buffering options since VGA video RAM is restricted to
  400.     64K.
  401.  
  402.   See Also:
  403.     What is double buffering ?
  404.  
  405.   x_hide_splitscreen
  406.   ------------------
  407.  
  408.   C Prototype: extern void x_hide_splitscreen(void);
  409.  
  410.  
  411.   This function hides an existing split screen by setting its starting
  412.   scan line to the last physical screen scan line.
  413.   "ScreenPhysicalHeight" is adjusted but the "SplitScreenScanLine" is not
  414.   altered as it is required for restoring the split screen at a later stage.
  415.  
  416.   WARNING: Only to be used if SplitScrnLine has been previously called
  417.        Disabled for mode 5-11 (320x400-376x564). The memory for
  418.         the initial split screen is reserved and the size limitations
  419.        of these modes means any change in the split screen scan line
  420.            will encroach on the split screen ram
  421.            Update: Now disabled for these modes
  422.  
  423.   See Also:
  424.  
  425.     What is a split screen ?
  426.  
  427.   x_show_splitscreen
  428.   ------------------
  429.  
  430.   C Prototype: extern void x_show_splitscreen(void);
  431.  
  432.   Restores split screen start scan line to the initial split screen
  433.   starting scan line as set by "SplitScrnScanLine".
  434.   "ScreenPhysicalHeight" is adjusted.
  435.  
  436.   WARNING: Only to be used if SplitScrnLine has been previously called
  437.        Disabled for mode 4-10 (320x400-376x564). The memory for
  438.         the initial split screen is reserved and the size limitations
  439.         of these modes means any change in the split screen scan line
  440.            will encroach on the split screen ram
  441.  
  442.  
  443.   x_adjust_splitscreen
  444.   --------------------
  445.  
  446.   C Prototype: extern void x_adjust_splitscreen(WORD line);
  447.  
  448.   line - The scan line at which the split screen is to start.
  449.  
  450.   Sets the split screen start scan line to a new scan line. Valid scan lines
  451.   are between the initial split screen starting scan line and the last
  452.   physical screen scan line. "ScreenPhysicalHeight" is also adjusted.
  453.  
  454.   WARNING: Only to be used if SplitScrnLine has been previously called
  455.        Disabled for mode 4-10 (320x400-376x564). The memory for
  456.         the initial split screen is reserved and the size limitations
  457.         of these modes means any change in the split screen scan line
  458.            will encroach on the split screen ram
  459.  
  460.   x_set_start_addr
  461.   ----------------
  462.  
  463.   C Prototype: extern void x_set_start_addr(WORD X,WORD Y);
  464.  
  465.     X,Y - coordinates of top left corner of physical screen within current
  466.       virtual screen.
  467.  
  468.   Set Mode X non split screen physical start address within current virtual
  469.   page.
  470.  
  471.   X must not exceed (Logical screen width - Physical screen width)
  472.   ie "MaxScrollX" and Y must not exceed (Logical screen height -
  473.   Physical screen height) ie "MaxScrollY"
  474.  
  475.   x_page_flip
  476.   -----------
  477.  
  478.   C Prototype: extern void x_page_flip(WORD X,WORD Y);
  479.  
  480.     X,Y - coordinates of top left corner of physical screen within the
  481.       the hidden virtual screen if double buffering is active, or
  482.       the current virtual screen otherwise.
  483.  
  484.   Sets the physical screen start address within currently hidden virtual
  485.   page and then flips pages. If double buffering is not active then this
  486.   function is functionally equivalent to "x_set_start_addr".
  487.  
  488.   X must not exceed (Logical screen width - Physical screen width)
  489.   ie "MaxScrollX" and Y must not exceed (Logical screen height -
  490.   Physical screen height) ie "MaxScrollY"
  491.  
  492.   x_text_mode
  493.   -----------
  494.  
  495.   C Prototype: extern void x_text_mode(void);
  496.  
  497.   Disables graphics mode.
  498.  
  499.   x_set_cliprect
  500.   --------------
  501.  
  502.   C Prototype: extern void x_set_cliprect(WORD left,WORD top,WORD right,
  503.         WORD bottom);
  504.  
  505.   Defines the clipping rectangle for clipping versions of planar and video
  506.   bitmap puts.
  507.  
  508.   NOTE: Compiled bitmaps cannot be clipped.
  509.  
  510.  
  511. --------------------------------------------------------------------------
  512. MODULE XPOINT
  513. --------------------------------------------------------------------------
  514.  
  515.   Point functions all MODE X 256 Color resolutions
  516.  
  517.   ASM SOURCES
  518.  
  519.     xpoint.asm xpoint.inc xlib.inc model.inc
  520.  
  521.   C HEADER FILE
  522.  
  523.    xpoint.h
  524.  
  525.   EXPORTED FUNCTIONS
  526.  
  527.   x_put_pix
  528.   ---------
  529.  
  530.   C Prototype: extern void x_put_pix(WORD X,WORD Y,WORD PageOffset,
  531.                                      WORD Color);
  532.  
  533.   Draw a point of specified colour at coordinates X,Y
  534.   within the virtual page starting at offset PageOffset.
  535.  
  536.   x_get_pix
  537.   ---------
  538.  
  539.   C Prototype: extern WORD x_get_pix(WORD X, WORD Y, WORD PageBase);
  540.  
  541.   Read a point of at coordinates X,Y within the virtual page starting
  542.   at offset PageOffset.
  543.  
  544.  
  545. --------------------------------------------------------------------------
  546. MODULE XRECT
  547. --------------------------------------------------------------------------
  548.  
  549.   Screen rectangle display and manipulation functions
  550.  
  551.   ASM SOURCES
  552.  
  553.     xrect.asm xrect.inc xlib.inc model.inc
  554.  
  555.   C HEADER FILE
  556.  
  557.     xrect.h
  558.  
  559.  
  560.   EXPORTED FUNCTIONS
  561.  
  562.   x_rect_pattern
  563.   --------------
  564.  
  565.   C Prototype: extern void x_rect_pattern(WORD StartX, WORD StartY,
  566.                                           WORD EndX, WORD EndY,
  567.                                           WORD PageBase,BYTE far *Pattern);
  568.  
  569.   StartX,StartY - Coordinates of upper left hand corner of rectangle
  570.   EndX,EndY     - Coordinates of lower right hand corner of rectangle
  571.   PageBase      - Offset of virtual screen
  572.   *Pattern      - Pointer to the user defined pattern (16 bytes)
  573.  
  574.  
  575.   Mode X rectangle 4x4 pattern fill routine.
  576.  
  577.   Upper left corner of pattern is always aligned to a multiple-of-4
  578.   row and column. Works on all VGAs. Uses approach of copying the
  579.   pattern to off-screen display memory, then loading the latches with
  580.   the pattern for each scan line and filling each scan line four
  581.   pixels at a time. Fills up to but not including the column at EndX
  582.   and the row at EndY. No clipping is performed.
  583.  
  584.   Based on code originally published in DDJ Mag by M. Abrash
  585.  
  586.   Warning the VGA memory locations PATTERN_BUFFER (A000:FFFc) to
  587.   A000:FFFF are reserved for the pattern buffer
  588.  
  589.  
  590.   See Also:
  591.     Doctor Dobbs Journal references.
  592.  
  593.  
  594.   x_rect_pattern_clipped
  595.   ----------------------
  596.  
  597.   As above but clipped.
  598.  
  599.   x_rect_fill
  600.   -----------
  601.  
  602.   C Prototype: extern void x_rect_fill(WORD StartX,WORD StartY,
  603.                                        WORD EndX,WORD EndY,
  604.                                        WORD PageBase,WORD color);
  605.  
  606.   StartX,StartY - Coordinates of upper left hand corner of rectangle
  607.   EndX,EndY - Coordinates of lower right hand corner of rectangle
  608.   PageBase - Offset of virtual screen
  609.   Color -color to use for fill
  610.  
  611.   Mode X rectangle solid color fill routine.
  612.   Based on code originally published in DDJ Mag by M. Abrash
  613.  
  614.   See Also:
  615.     Doctor Dobbs Journal references.
  616.  
  617.   x_rect_fill_clipped
  618.   -------------------
  619.  
  620.   as above but clipped.
  621.  
  622.  
  623.   x_cp_vid_rect
  624.   -------------
  625.  
  626.   C Prototype: extern void x_cp_vid_rect(WORD SourceStartX,WORD SourceStartY,
  627.                           WORD SourceEndX,WORD SourceEndY,
  628.                           WORD DestStartX,WORD DestStartY,
  629.                           WORD SourcePageBase,WORD DestPageBase,
  630.                           WORD SourceBitmapWidth,WORD DestBitmapWidth);
  631.  
  632.   StartX,StartY- Coordinates of upper left hand corner of source rectangle
  633.   EndX,EndY    - Coordinates of lower right hand corner of source rectangle
  634.   DestStartX,DestStartY - Coordinates of rectangle destination
  635.   SourcePageBase        - source rectangle page offset
  636.   DestPageBase          - destination rectangles page offset
  637.   SourceBitmapWidth     - width of bitmap within the source virtual screen
  638.                           containing the source rectangle
  639.   DestBitmapWidth       - width of bitmap within the dest. virtual screen
  640.                           containing the destination rectangle
  641.  
  642.   Mode X display memory to display memory copy
  643.   routine. Left edge of source rectangle modulo 4 must equal left edge
  644.   of destination rectangle modulo 4. Works on all VGAs. Uses approach
  645.   of reading 4 pixels at a time from the source into the latches, then
  646.   writing the latches to the destination. Copies up to but not
  647.   including the column at SrcEndX and the row at SrcEndY. No
  648.   clipping is performed. Results are not guaranteed if the source and
  649.   destination overlap.
  650.  
  651.  
  652.   Based on code originally published in DDJ Mag by M. Abrash
  653.  
  654.   See Also:
  655.     Doctor Dobbs Journal references.
  656.  
  657.   x_shift_rect
  658.   ------------
  659.  
  660.   C Prototype:
  661.   extern void x_shift_rect (WORD SrcLeft, WORD SrcTop,
  662.             WORD SrcRight, WORD SrcBottom,
  663.             WORD DestLeft, WORD DestTop, WORD ScreenOffs);
  664.  
  665.   SrcLeft, SrcTop - Coordinates of upper left hand corner of rectangle
  666.   SrcRight, SrcBottom - Coordinates of lower right hand corner of rectangle
  667.   DestLeft, DestTop - Coordinates of upper left corner of destination
  668.   ScreenOffs    - Offset of virtual screen
  669.  
  670.   This function copies a rectangle of VRAM onto another area of VRAM,
  671.   even if the destination overlaps with the source.  It is designed
  672.   for scrolling text up and down, and for moving large areas of screens
  673.   around in tiling systems.  It rounds all horizontal coordinates to
  674.   the nearest byte (4-column chunk) for the sake of speed.  This means
  675.   that it can NOT perform smooth horizontal scrolling.  For that,
  676.   either scroll the whole screen (minus the split screen), or copy
  677.   smaller areas through system memory using the functions in the
  678.   XPBITMAP module.
  679.  
  680.   SrcRight is rounded up, and the left edges are rounded down, to
  681.   ensure that the pixels pointed to by the arguments are inside the
  682.   the rectangle.  That is, SrcRight is treated as (SrcRight+3) >> 2,
  683.   and SrcLeft as SrcLeft >> 2.
  684.  
  685.   The width of the rectangle in bytes (width in pixels / 4)
  686.   cannot exceed 255.
  687.  
  688. ---------------------------------------------------------------------------
  689. MODULE XPAL
  690. ---------------------------------------------------------------------------
  691.  
  692.     Palette functions for VGA 256 color modes.
  693.  
  694.     All the functions in this module operate on two variations of the
  695.     pallete buffer, the raw and annotated buffers.
  696.  
  697.     All those functions ending in "raw" operate on the following palette
  698.     structure:
  699.  
  700.        BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
  701.  
  702.     No reference to the starting colour index or number of colours stored
  703.     is contained in the structure.
  704.  
  705.     All those functions ending in "struc" operate on the following palette
  706.     structure:
  707.  
  708.        BYTE:c,BYTE:n,BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
  709.  
  710.     where c is the starting colour and n is the number of colours stored
  711.  
  712.  
  713.     WARNING: There is no validity checking in these functions. The onus is
  714.     on the user to supply valid parameters to the functions.
  715.  
  716.  
  717.   ASM SOURCES
  718.  
  719.     xpal.asm xpal.inc xlib.inc model.inc
  720.  
  721.   C HEADER FILE:
  722.  
  723.     xpal.h
  724.  
  725.   EXPORTED FUNCTIONS
  726.  
  727.   x_get_pal_raw
  728.   -------------
  729.  
  730.   C Prototype: extern void x_get_pal_raw(BYTE far * pal,WORD num_colrs,
  731.                                          WORD start_index);
  732.  
  733.   Read DAC palette into raw buffer with interrupts disabled
  734.   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
  735.  
  736.   WARNING: Memory for the palette buffers must all be pre-allocated.
  737.  
  738.   x_get_pal_struc
  739.   ---------------
  740.  
  741.   C Prototype: extern void x_get_pal_struc(BYTE far * pal,WORD num_colrs,
  742.                                               WORD start_index);
  743.  
  744.   Read DAC palette into annotated type buffer with interrupts disabled
  745.   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
  746.  
  747.   WARNING: memory for the palette buffers must all be pre-allocated
  748.  
  749.   x_put_pal_raw
  750.   -------------
  751.  
  752.   C Prototype: extern void x_put_pal_raw(BYTE far * pal,WORD num_colrs,
  753.                                          WORD start_index);
  754.  
  755.   Write DAC palette from raw buffer with interrupts disabled
  756.   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
  757.  
  758.   x_put_pal_struc
  759.   --------------
  760.  
  761.   C Prototype: extern void x_put_pal_struc(BYTE far * pal);
  762.  
  763.   Write DAC palette from annotated type buffer with interrupts disabled
  764.   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
  765.  
  766.   x_set_rgb
  767.   ---------
  768.  
  769.   C Prototype: extern x_set_rgb(BYTE color,BYTE red_c,BYTE green_c,
  770.                                BYTE blue_c);
  771.  
  772.   Set the RGB components of a vga color
  773.  
  774.   x_rot_pal_struc
  775.   ---------------
  776.  
  777.   C Prototype: extern void x_rot_pal_struc(BYTE far * pal,WORD direction);
  778.  
  779.   Rotate annotated palette buffer entries. Direction 0 = backward,
  780.   1 = forward.
  781.  
  782.   x_rot_pal_raw
  783.   -------------
  784.  
  785.   C Prototype: extern x_rot_pal_raw(BYTE far * pal,WORD direction,
  786.                                     WORD num_colrs);
  787.  
  788.   Rotate a raw palette buffer. Direction 0 = backward,
  789.   1 = forward.
  790.  
  791.   x_put_contrast_pal_struc
  792.   ------------------------
  793.  
  794.   C Prototype: extern  void x_put_contrast_pal_struc(BYTE far * pal,
  795.                BYTE  intensity);
  796.  
  797.   Write DAC palette from annotated type buffer with specified intensity
  798.   adjustment (ie palette entries are decremented where possible by
  799.   "intensity" units).
  800.  
  801.   Designed for fading in or out a palette without using an intermediate
  802.   working palette buffer ! (Slow but memory efficient ... OK for small
  803.   pal strucs}
  804.  
  805.  
  806.   x_transpose_pal_struc
  807.   ---------------------
  808.  
  809.   C Prototype: extern void x_transpose_pal_struc(BYTE far * pal,
  810.                                                  WORD StartColor);
  811.  
  812.   Write DAC palette from annotated type buffer with interrupts disabled
  813.   starting at a new palette index.
  814.  
  815.  
  816.   x_cpcontrast_pal_struc
  817.   ----------------------
  818.  
  819.   C Prototype: extern WORD x_cpcontrast_pal_struc(BYTE far *src_pal,
  820.                                 BYTE far *dest_pal,BYTE Intensity);
  821.  
  822.   Copy one annotated palette buffer to another making the intensity
  823.   adjustment. Used in fading in and out fast and smoothly.
  824.  
  825. ---------------------------------------------------------------------------
  826. MODULE XLINE
  827. ---------------------------------------------------------------------------
  828.  
  829.   Line Drawing functions.
  830.  
  831.   ASM SOURCES
  832.  
  833.     xline.asm xline.inc xlib.inc model.inc
  834.  
  835.   C HEADER FILE
  836.  
  837.     xline.h
  838.  
  839.   EXPORTED FUNCTIONS
  840.  
  841.   x_line
  842.   ------
  843.  
  844.   C Prototype: extern void x_line(WORD x0,WORD y0,WORD x1,WORD y1,
  845.                   WORD color,WORD PageBase);
  846.  
  847.   Draw a line with the specified end points in the page starting at
  848.   offset "PageBase".
  849.  
  850.   No Clipping is performed.
  851.  
  852. ---------------------------------------------------------------------------
  853. MODULE XTEXT
  854. ---------------------------------------------------------------------------
  855.  
  856.   ASM SOURCES
  857.  
  858.     xtext.asm xtext.inc xlib.inc model.inc
  859.  
  860.   C HEADER FILE
  861.  
  862.     xtext.h
  863.  
  864.   MACROS
  865.  
  866.    FONT_8x8  0
  867.    FONT_8x15 1
  868.    FONT_USER 2
  869.  
  870.   EXPORTED VARIABLES
  871.  
  872.     NOTE: All variables are read only. I you modify them the results may
  873.     be unpredictable.
  874.  
  875.     CharHeight - BYTE - Height of current inbuilt character set
  876.  
  877.     CharWidth  - BYTE - Width of current inbuilt character set
  878.  
  879.     FirstChar  - BYTE - First character of current inbuilt character set
  880.  
  881.     UserCharHeight - BYTE - Height of current user character set
  882.  
  883.     UserCharWidth - BYTE - Width of current user character set
  884.  
  885.     UserFirstCh - BYTE - First character of current user character set
  886.  
  887.  
  888.   EXPORTED FUNCTIONS
  889.  
  890.   x_text_init
  891.   -----------
  892.  
  893.   C Prototype: extern WORD x_text_init(void);
  894.  
  895.   Initializes the Mode X text driver and sets the default font (VGA ROM 8x8)
  896.  
  897.   x_set_font
  898.   ----------
  899.  
  900.   C Prototype: extern void x_set_font(WORD FontId);
  901.  
  902.   Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14
  903.   2 = User defined bitmapped font.
  904.  
  905.   WARNING: A user font must be registered before setting FontID 2
  906.  
  907.   See Also:
  908.  
  909.     Defines for this module
  910.  
  911.   x_register_userfont
  912.   -------------------
  913.  
  914.   C Prototype: extern void x_register_userfont(char far *UserFontPtr);
  915.  
  916.  
  917.   Register a user font for later selection. Only one user font can be
  918.   registered at any given time. Registering a user font deregisters the
  919.   previous user font. User fonts may be at most 8 pixels wide.
  920.  
  921.   USER FONT STRUCTURE
  922.  
  923.   Word:  ascii code of first char in font
  924.   Byte:  Height of chars in font
  925.   Byte:  Width of chars in font
  926.   n*h*Byte: the font data where n = number of chars and h = height
  927.       of chars
  928.  
  929.   WARNING: The onus is on the program to ensure that all characters
  930.            drawn whilst this font is active, are within the range of
  931.            characters defined.
  932.  
  933.   x_put_char
  934.   ----------
  935.  
  936.   C Prototype: extern void x_put_char(char ch,WORD X,WORD Y,WORD PgOffs,
  937.                       WORD Color);
  938.  
  939.   Draw a text character at the specified location with the specified
  940.   color.
  941.  
  942.   ch       -  char to draw
  943.   x,y      -  screen coords at which to draw ch
  944.   ScrnOffs -  Starting offset of page on whih to draw
  945.   Color    -  Color of the text
  946.  
  947.   WARNING: InitTextDriver must be called before using this function
  948.  
  949.  
  950.   **** NOTE ****
  951.  
  952.   The file "xprintf.c" implements a printf style formatted output function
  953.  
  954.   x_printf
  955.   --------
  956.  
  957.   C Prototype: void x_printf(int x,int y,unsigned ScrnOffs,int color,
  958.            char *ln,...);
  959.  
  960.   x,y      -  screen coords at which to draw ch
  961.   ScrnOffs -  Starting offset of page on whih to draw
  962.   Color    -  Color of the text
  963.  
  964.   Parameters beyond Color conform to the standard printf parameters.
  965.  
  966.   x_bgprintf
  967.   ----------
  968.  
  969.   C Prototype: void x_bgprintf(int x,int y,unsigned ScrnOffs,int fgcolor,
  970.            int bgcolor, char *ln,...);
  971.  
  972.   x,y      -  screen coords at which to draw ch
  973.   ScrnOffs -  Starting offset of page on whih to draw
  974.   fgcolor    -  Color of the text foreground
  975.   bgcolor    -  Color of the text background
  976.  
  977.   Parameters beyond bgolor conform to the standard printf parameters.
  978.  
  979.  
  980.   x_get_char_width
  981.   ----------------
  982.  
  983.   C Prototype: unsigned int x_get_char_width(char ch)
  984.  
  985.   ch - character to get width of
  986.  
  987. --------------------------------------------------------------------------
  988. MODULE XPBITMAP
  989. --------------------------------------------------------------------------
  990.  
  991.   This module implements a set of functions to operate on planar bitmaps.
  992.   Planar bitmaps as used by these functions have the following structure:
  993.  
  994.   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  995.   BYTE 1                 The bitmap height in rows range 1..255
  996.   BYTE 2..n1             The plane 0 pixels width*height bytes
  997.   BYTE n1..n2            The plane 1 pixels width*height bytes
  998.   BYTE n2..n3            The plane 2 pixels width*height bytes
  999.   BYTE n3..n4            The plane 3 pixels width*height bytes
  1000.  
  1001.   These functions provide the fastest possible bitmap blts from system ram to
  1002.   to video and further, the single bitmap is applicable to all pixel
  1003.   allignments. The masked functions do not need separate masks since all non
  1004.   zero pixels are considered to be masking pixels, hence if a pixel is 0 the
  1005.   corresponding screen destination pixel is left unchanged.
  1006.  
  1007.  
  1008.   ASM SOURCES
  1009.  
  1010.     xpbitmap.asm xpbitmap.inc xlib.inc model.inc
  1011.  
  1012.   C HEADER FILE
  1013.  
  1014.     xpbitmap.h
  1015.  
  1016.   EXPORT FUNCTIONS
  1017.  
  1018.   x_put_masked_pbm
  1019.   ----------------
  1020.  
  1021.   C Prototype: extern void x_put_masked_pbm(WORD X,WORD Y,WORD ScrnOffs,
  1022.                  BYTE far * Bitmap);
  1023.  
  1024.   Mask write a planar bitmap from system ram to video ram. All zero source
  1025.   bitmap bytes indicate destination byte to be left unchanged.
  1026.  
  1027.   Source Bitmap structure:
  1028.  
  1029.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  1030.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  1031.  
  1032.   NOTE: width is in bytes ie lots of 4 pixels
  1033.  
  1034.   LIMITATIONS: No clipping is supported
  1035.                Only supports bitmaps with widths which are a multiple of
  1036.                4 pixels
  1037.  
  1038.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1039.      functions.
  1040.  
  1041.   x_put_pbm
  1042.   ---------
  1043.  
  1044.   C Prototype: extern void x_put_pbm(WORD X, WORD Y, WORD ScrnOffs,
  1045.                  BYTE far * Bitmap);
  1046.  
  1047.   Write a planar bitmap from system ram to video ram.
  1048.  
  1049.   Source Bitmap structure:
  1050.  
  1051.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  1052.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  1053.  
  1054.   NOTE: width is in bytes ie lots of 4 pixels
  1055.  
  1056.   LIMITATIONS: No clipping is supported
  1057.                Only supports bitmaps with widths which are a multiple of
  1058.            4 pixels
  1059.  
  1060.  
  1061.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1062.      functions.
  1063.  
  1064.   x_get_pbm
  1065.   ---------
  1066.  
  1067.   C Prototype: extern void x_get_pbm(WORD X, WORD Y,BYTE Bw,BYTE Bh,
  1068.                WORD ScrnOffs, BYTE far * Bitmap);
  1069.  
  1070.   Read a planar bitmap to system ram from video ram.
  1071.  
  1072.   Source Bitmap structure:
  1073.  
  1074.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  1075.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  1076.  
  1077.   NOTE: width is in bytes ie lots of 4 pixels
  1078.  
  1079.   LIMITATIONS: No clipping is supported
  1080.                Only supports bitmaps with widths which are a multiple of
  1081.                4 pixels
  1082.  
  1083.  
  1084.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1085.      functions.
  1086.  
  1087. --------------------------------------------------------------------------
  1088. MODULE XPBMCLIP
  1089. --------------------------------------------------------------------------
  1090.  
  1091.   This module implements a similar set of functions to operate on planar
  1092.   bitmaps as "XPBITMAP" but incorporates clipping to a user defined
  1093.   clipping rectangle (which is set by "x_set_cliprect" in module xmain).
  1094.  
  1095.   The planar bitmap format is identical to the above module
  1096.  
  1097.   There are three variations of the functions in XPBITMAP in this module
  1098.   identified by the three function name extensions: _clipx, _clipy _clipxy.
  1099.   Because speed is critical in games programming you do not want to be
  1100.   checking for clipping if not necessary thus for sprites that move only
  1101.   horizontally you would use the _clipx version of the put function,
  1102.   for sprites that move vertically you would use the _clipy version and for
  1103.   sprites that move both directions you would use the clipxy version.
  1104.   Keep in mind also that the clipping components of these functions assume
  1105.   that the clipping rectangle is equal to or larger than the size of the
  1106.   bitmap ie. if a bitmap is top clipped, it is assumed that the bitmap's
  1107.   bottom is not also clipped. Similarly with horizontal clipping.
  1108.  
  1109.   Note: performance in decreasing order is as follows.
  1110.     _clipy,_clipx,_clipxy with masked puts being slower than unmasked
  1111.     puts
  1112.  
  1113.   Horizontal clipping is performed to byte boundaries (4 pixels) rather than
  1114.   pixels. This allows for the fastest implementation of the functions. It is
  1115.   not such a handicap because for one, your screen width a multiple of 4
  1116.   pixels wide and  for most purposes it is the screen edges that form the
  1117.   clipping rectangle.
  1118.  
  1119.   Following is an example of setting a clipping rectangle to the logical
  1120.   screen edges:
  1121.  
  1122.   x_set_cliprect(0,0,ScrnLogicalByteWidth,ScrnLogicalHeight)
  1123.  
  1124.    NOTE: the functions now return a value;
  1125.       1 if clipped image is fully clipped (ie no portion of it
  1126.       appears on the screen) otherwise it returns 0
  1127.  
  1128.  
  1129.   ASM SOURCES
  1130.  
  1131.     xpbmclip.asm xpbmclip.inc xlib.inc model.inc
  1132.  
  1133.   C HEADER FILE
  1134.  
  1135.     xpbmclip.h
  1136.  
  1137.   EXPORT FUNCTIONS
  1138.  
  1139.   x_put_pbm_clipx
  1140.   ---------------
  1141.   x_put_pbm_clipy
  1142.   ---------------
  1143.   x_put_pbm_clipxy
  1144.   ----------------
  1145.   x_put_masked_pbm_clipx
  1146.   ----------------------
  1147.   x_put_masked_pbm_clipy
  1148.   ----------------------
  1149.   x_put_masked_pbm_clipxy
  1150.   -----------------------
  1151.  
  1152.   For a detailed description of parameters etc. see equivalent functions
  1153.   in module "XPBITMAP".
  1154.  
  1155.  
  1156. --------------------------------------------------------------------------
  1157. MODULE  XCBITMAP
  1158. --------------------------------------------------------------------------
  1159.  
  1160.                                  XCBITMAP:
  1161.                The Care and Feeding of Compiled Masked Blits
  1162.                            by Matthew MacKenzie
  1163.  
  1164. The XCBITMAP module of the Xlib library is made up of the files
  1165. XCBITMAP.ASM, XCBITMAP.INC, and XCBITMAP.H.
  1166.  
  1167. The XCBITMAP module is small, containing only three procedures:
  1168.   o  x_compile_bitmap compiles your bitmap into native code which writes
  1169.      to the VGA screen in an X mode.
  1170.   o  x_put_cbitmap converts X and Y coordinates into a location on the
  1171.      screen, sets up the necessary VGA registers, and executes the compiled
  1172.      bitmap as a subroutine.
  1173.   o  x_sizeof_cbitmap takes a planar bitmap and returns an integer equal to
  1174.      the size of the compiled bitmap which the planar bitmap would produce.
  1175.      It is essentially a lobotomized version of x_compile_bitmap, with all
  1176.      the code generation replaced with a size counter.
  1177.  
  1178.     x_compile_bitmap scans through a source bitmap and generates 8086
  1179. instructions to plot every nonzero pixel.  It is designed to be used
  1180. before the action begins rather than on-the-fly.  The compiled bitmap
  1181. contains no branches, and no reference to the zero (transparent) pixels.
  1182. Where two pixels are exactly four columns apart they are plotted with a
  1183. single 16-bit store, and the VGA MAP_MASK register will be set at most
  1184. four times.  As a result your bitmap may run several times faster than a
  1185. traditional memory-to-VGA masked blit routine.
  1186.     There is no way to perform clipping on these bitmaps, or to plot a
  1187. pixel of color zero.
  1188.     x_compile_bitmap works with bitmaps in the standard Xlib planar bitmap
  1189. format.  On a time scale of 60 frames per second, it is actually relatively
  1190. slow.  Since a compiled bitmap is relocatable you may just want to have it
  1191. saved to disk, and not include the source bitmap in your program at all.
  1192.     The source bitmap format is an array of bytes, a little like this:
  1193.  
  1194. char eye[] ={4, 7,  /* four byte columns across, seven rows tall */
  1195.        0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0,
  1196.        0, 0, 9, 9, 1, 1, 1, 4, 4, 9, 9, 0, 0, 0, 0, 0,
  1197.        0, 9, 9, 1, 2, 0, 0, 4, 4, 1, 9, 9, 0, 0, 0, 0,
  1198.        9, 9, 9, 1, 0, 0, 0, 0, 1, 1, 9, 9, 9, 0, 0, 0,
  1199.        0, 9, 9, 1, 2, 0, 0, 2, 1, 1, 9, 9, 0, 0, 0, 0,
  1200.        0, 0, 9, 9, 1, 1, 1, 1, 1, 9, 9, 0, 0, 0, 0, 0,
  1201.        0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0};
  1202.  
  1203.     This is actually a linear bitmap, which is the wrong format for
  1204. compilation, but is easier on human eyes.  Use the module XBMTOOLS to
  1205. convert linear bitmaps into planar bitmaps, and vice-versa.
  1206.     To compile this image for a mode 360 pixels (90 byte columns) across:
  1207.  
  1208. char planar_eye[4*7 + 2];
  1209. char far * EyeSize;
  1210.  
  1211. (void) x_bm_to_pbm((char far *) eye, (char far *) planar_eye);
  1212. EyeSize = x_sizeof_cbitmap((far char *) planar_eye);
  1213. CompiledEye = farmalloc(EyeSize);
  1214. (void) x_compile_bitmap(90, (far char *) planar_eye, CompiledEye);
  1215.  
  1216.     Notice that both buffers must exist beforehand.  Since x_compile_bitmap
  1217. returns the size of the compiled code, in bytes, you can reallocate the
  1218. bitmap immediately to the right size if using x_sizeof_xbitmap seems
  1219. inconvenient (reallocation may even be faster, though using the function is
  1220. cleaner).  The pointers are 32-bit because compiled bitmaps take so much
  1221. space: they are at one end of the speed-versus-memory spectrum.  A good
  1222. rule of thumb is to allocate (3.5 x buffer-height x buffer-width) + 25
  1223. bytes (rounding up ;-), then pare your bitmap down when you find out how
  1224. much space you've actually used.
  1225.     Since the compiled bitmap has to fit within one segment of memory, it
  1226. cannot contain more than about 19,000 pixels.  This will not be a
  1227. limitation for most sane programmers.  If you are not a sane programmer try
  1228. splitting your huge, unwieldy image up into smaller parts -- you can use
  1229. the same gigantic bitmap if you divide it into horizontal slices for
  1230. compilation.  For that matter, dividing the source up that way will let
  1231. you use a source bitmap large than 64K, which is an even sicker idea...
  1232.     Back to business.  A bitmap is compiled for only one width of screen.
  1233. If you are using a logical screen larger than your physical screen, call
  1234. the bitmap compiler with the logical width -- the important thing is the
  1235. number of bytes per line.  Notice that you do not have to be in a graphics
  1236. mode to use this routine.  This allows you to develop and compile bitmaps
  1237. separately, with whatever utility programs you might cook up.
  1238.  
  1239.     The final function is x_put_cbitmap.  To plot our eye at (99,4), on
  1240. the page which starts at location 0:
  1241. x_put_cbitmap(99, 4, 0, CompiledEye);
  1242.     This function depends on the global variable ScrnLogicalByteWidth from
  1243. the module XMAIN, which should be the same number as the column parameter
  1244. you used to compile your bitmap.
  1245.     The XCBITMAP module supports memory-to-VGA blits only.  Xlib also
  1246. includes non-masking routines which can quickly save and restore the
  1247. background screen behind your bitmap, using fast string operations.
  1248.  
  1249.    This module is part of the Xlib package, and is in the public domain.
  1250. If you write something which uses it, though, please send me a copy as a
  1251. courtesy -- if for no other reason so I can tilt my chair back and reflect
  1252. that it may have been worth the trouble after all.
  1253.  
  1254. The included program DEMO2.C demonstrates the performance difference
  1255. between planar bitmap masked blits and compiled bitmap blits.
  1256.  
  1257. --------------------------------------------------------------------------
  1258. MODULE XCOMPPBM
  1259. --------------------------------------------------------------------------
  1260.  
  1261. Identical to XCBITMAP except that the source bitmaps are the PBM form
  1262. rather than LBM.
  1263.  
  1264. FUNCTIONS
  1265.  
  1266. x_compile_pbm
  1267. -------------
  1268. x_sizeof_cpbm
  1269. -------------
  1270.  
  1271. See XCBITMAP module
  1272.  
  1273. --------------------------------------------------------------------------
  1274. MODULE XVBITMAP
  1275. --------------------------------------------------------------------------
  1276.  
  1277. The XVBITMAP module implements yet another type of bitmap to complement
  1278. planar and compiled bitmaps, VRAM based bitmaps. If a 4 cylinder car is
  1279. analagous to planar bitmaps, that is thrifty on memory consumption but low
  1280. performance and and a V8 is analagous to Compiled bitmaps, memory guzzlers
  1281. that really fly, then VRAM based bitmaps are the 6 cylinder modest performers
  1282. with acceptable memory consumption.
  1283.  
  1284. To summarise their selling points, VBM's are moderately fast with fair memory
  1285. consumption, and unlike compiled bitmaps, can be clipped. The disadvantages
  1286. are that they are limited by the amount of free video ram and have a complex
  1287. structure.
  1288.  
  1289. The VRAM bitmap format is rather complex consisting of components stored in
  1290. video ram and components in system ram working together. This complexity
  1291. necessitates the existence of a creation function "x_make_vbm" which takes
  1292. an input linear bitmap and generates the equivalent VBM (VRAM Bit Map).
  1293.  
  1294. VBM structure:
  1295.  
  1296.       WORD  0   Size          Total size of this VBM structure in bytes
  1297.       WORD  1   ImageWidth    Width in bytes of the image (for all alignments)
  1298.       WORD  2   ImageHeight   Height in scan lines of the image
  1299.  
  1300.       WORD  3 Alignment 0  ImagePtr   Offset in VidRAM of this aligned image
  1301.    +--WORD  4              MaskPtr    Offset (within this structure's DS) of
  1302.    |   .                   alignment masks
  1303.    |   .
  1304.    |   .
  1305.    |  WORD  9 Alignment 3  ImagePtr   Offset in VidRAM of this aligned image
  1306.   +|--WORD 10              MaskPtr    Offset (within this structure's DS) of
  1307.   ||                              alignment masks
  1308.   ||
  1309.   |+->BYTE 21 (WORD 11)                -------+-- Image masks for alignment 0
  1310.   |   .                                       |
  1311.   |   .                                       |
  1312.   |   BYTE  21 + ImageWidth*ImageHeight  -----+
  1313.   |
  1314.   |   .
  1315.   |   . (similaly for alignments 1 - 2 )
  1316.   |   .
  1317.   |
  1318.   +-->BYTE  21 + 3*ImageWidth*ImageHeight + 1-+-- Image masks for alignment 3
  1319.       .                                       |
  1320.       .                                       |
  1321.       BYTE  21 + 4*(ImageWidth*ImageHeight) --+
  1322.  
  1323.       .
  1324.       .
  1325.       << Similarly for alignments 2 and 3 >>
  1326.       .
  1327.       .
  1328.       BYTE 21 + 4*(ImageWidth*ImageHeight)
  1329.   -------------
  1330.  
  1331.   (And dont forget the corresponding data in video ram)
  1332.  
  1333. You can see for yourself the complexity of this bitmap format. The image
  1334. is stored in video ram in its 4 different alignments with pointers to these
  1335. alignments in the VBM. Similarly there are 4 alignments of the corresponding
  1336. masks within the VBM itself (towards the end). The mask bytes contain the
  1337. plane settings for the corresponding video bytes so that one memory move can
  1338. move up to 4 pixels at a time (depending on the mask settings) using the
  1339. VGA's latches, theoretically giving you a 4x speed improvement over
  1340. conventional blits like the ones implemented in "XPBITMAP". In actual fact
  1341. its anywhere between 2 and 3 due to incurred overheads.
  1342.  
  1343. These bitmaps are more difficult to store in files than PBM'S and CBM's but
  1344. still posible with a bit of work, so do not dismiss these as too difficult
  1345. to use. Consider all the bitmap formats carefully before deciding on which
  1346. to use. There may even be situations that a careful application of all three
  1347. types would be most effective ie. compiled bitmaps for Background tiles and
  1348. the main game character (which never need clipping), VRAM based bitmaps for
  1349. the most frequently occuring (oponent, alien etc) characters which get
  1350. clipped as they come into and leave your current location and planar bitmaps
  1351. for smaller or less frequently encountered characters.
  1352.  
  1353. ASM SOURCES
  1354.  
  1355.     xvbitmap.asm xvbitmap.inc xlib.inc model.inc
  1356.     xmakevbm.c  - Additional C module implementing creation function
  1357.  
  1358.   C HEADER FILE
  1359.  
  1360.     xvbitmap.h
  1361.  
  1362.   EXPORTED FUNCTIONS
  1363.  
  1364.   x_make_vbm
  1365.   ----------
  1366.  
  1367.   C Prototype: extern char far * x_make_vbm(char far *lbm, WORD *VramStart);
  1368.  
  1369.   Create the VBM from the given linear bitmap and place the image alignments
  1370.   in video ram starting at the offset in the variable pointed to by
  1371.   "VramStart". "VramStart" is then updated to point to the next free VRAM byte
  1372.   (just after the last byte of the image alignments). Usually you will point
  1373.   "VramStart" to "NonVisual_Offs".
  1374.  
  1375.    lbm         Pointer to the input linear bitmap
  1376.    VramStart   Pointer to variable containing Offset of first free VRAM byte
  1377.  
  1378.    x_put_masked_vbm
  1379.    ----------------
  1380.  
  1381.    C Prototype: extern int x_put_masked_vbm(int X, int Y, WORD ScrnOffs,
  1382.           BYTE far * VBitmap);
  1383.  
  1384.    Draw a VRAM based bitmap at (X,Y) relative to the screen with starting
  1385.    offset "ScrnOffs".
  1386.  
  1387.    Returns 1 if clipped image is fully clipped (ie no portion of it
  1388.    appears on the screen) otherwise it returns 0
  1389.  
  1390.    x_put_masked_vbm_clipx
  1391.    ----------------------
  1392.    x_put_masked_vbm_clipy
  1393.    ----------------------
  1394.    x_put_masked_vbm_clipxy
  1395.    -----------------------
  1396.  
  1397.      Clipping versions of "x_put_masked_vbm".
  1398.  
  1399.    See XPBMCLIP for more details on the type of clipping used as it is
  1400.    identical to XVBITMAP.
  1401.  
  1402. --------------------------------------------------------------------------
  1403. MODULE  XMOUSE
  1404. --------------------------------------------------------------------------
  1405. The XMOUSE module implements very basic mouse handling functions. The way
  1406. in which it operates is by installing an event handler function during
  1407. initialization which subsequently intercepts and processes mouse events and
  1408. automatically updates status variables such as mouse position and button
  1409. pressed status. It does not support the full functionality of:
  1410.  
  1411.   SPLIT SCREENS
  1412.   SCROLLED WINDOWS
  1413.   VIRTUAL WINDOWS
  1414.  
  1415. This was done to primarily prevent unecessary impedences to performance,
  1416. since the mouse handler function has the potential to degrade performance.
  1417. It also saves me alot of coding which I was too lazy to do.
  1418.  
  1419. Programs communicate with the mouse driver as with other devices, through
  1420. an interrupt vector namely 33h. On generating an interrupt, the mouse driver
  1421. expects a function number in AX and possibly other parameters in other
  1422. registers and returns information via the registers. A brief description
  1423. of the mouse functions follows:
  1424.  
  1425.           --------------------------------------
  1426.  
  1427.           MS Mouse Driver Functions
  1428.  
  1429.           Mouse Initialization                 0
  1430.           Show Cursor                          1
  1431.           Hide Cursor                          2
  1432.           Get Mouse Position & Button Status   3
  1433.           Set Mouse Cursor Position            4
  1434.           Get Button Press Information         5
  1435.           Get Button Release Information       6
  1436.           Set Min/Max Horizontal Position      7
  1437.           Set Min/Max Vertical Position        8
  1438.           Define Graphics Cursor Block         9
  1439.           Define Text Cursor                  10
  1440.           Read Mouse Motion Counters          11
  1441.           Define Event Handler                12
  1442.           Light Pen Emulation Mode ON         13
  1443.           Light Pen Emulation Mode OFF        14
  1444.           Set Mouse Mickey/Pixel Ratio        15
  1445.           Conditional Hide Cursor             16
  1446.           Set Double-Speed Threshold          19
  1447.           --------------------------------------
  1448.  
  1449. In practice only afew of these functions are used and even fewer when the
  1450. mouse status is monitored by an event handler function such as is used in
  1451. this module.
  1452.  
  1453. The most important thing to note when using the mouse module is that the
  1454. mouse event handler must be removed before exiting the program. It is a good
  1455. idea to have an exit function (see the C "atexit" function) and include the
  1456. line "x_mouse_remove();" along with any other pre-exit cleanup code.
  1457.  
  1458.  
  1459.   ASM SOURCES
  1460.  
  1461.     xmouse.asm xlib.inc model.inc
  1462.  
  1463.   C HEADER FILE
  1464.  
  1465.     xmouse.h
  1466.  
  1467.   EXPORTED VARIABLES
  1468.  
  1469.    MouseInstalled    - WORD - Indicates whether mouse handler installed
  1470.    MouseHidden       - WORD - Indicates whether mouse cursor is hidden
  1471.    MouseButtonStatus - WORD - Holds the mouse button status
  1472.    MouseX            - WORD - Current X position of mouse cursor
  1473.    MouseY            - WORD - Current Y position of mouse cursor
  1474.    MouseFrozen       - WORD - Disallows position updates if TRUE
  1475.    MouseColor        - BYTE - The mouse cursors colour
  1476.  
  1477.   EXPORTED FUNCTIONS
  1478.  
  1479.   x_mouse_init
  1480.   ------------
  1481.  
  1482.     C Prototype:  int x_mouse_init()
  1483.  
  1484.   Initialize the mouse driver functions and install the mouse event handler
  1485.   function. This is the first function you must call before using any of the
  1486.   mouse functions. This mouse code uses the fastest possible techniques to
  1487.   save and restore mouse backgrounds and to draw the mouse cursor.
  1488.  
  1489.   WARNING: This function uses and updates "NonVisual_Offset" to allocate
  1490.        video ram for the saved mouse background.
  1491.  
  1492.   LIMITATIONS: No clipping is supported horizontally for the mouse cursor
  1493.            No validity checking is performed for NonVisual_Offs
  1494.  
  1495.   **WARNING** You must Hide or at least Freeze the mouse cursor while drawing
  1496.           using any of the other XLIB modules since the mouse handler may
  1497.           modify vga register settings at any time. VGA register settings
  1498.           are not preserved which will result in unpredictable drawing
  1499.           behavior. If you know the drawing will occur away from the
  1500.           mouse cursor set MouseFrozen to TRUE (1), do your drawing
  1501.           then set it to FALSE (0). Alternatively call "x_hide_mouse",
  1502.           perform your drawing and then call "x_show_mouse". Another
  1503.           alternative is to disable interrupts while drawing but usually
  1504.           drawing takes up alot of time and having interrupts disabled
  1505.           for too long is not a good idea.
  1506.  
  1507.   x_define_mouse_cursor
  1508.   ---------------------
  1509.  
  1510.   C Prototype:
  1511.     void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)
  1512.  
  1513.     MouseDef - a pointer to 14 characters containing a bitmask for all the
  1514.            cursor's rows.
  1515.     MouseColor - The colour to use when drawing the mouse cursor.
  1516.  
  1517.   Define a mouse cursor shape for use in subsequent cursor redraws. XMouse
  1518.   has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.
  1519.  
  1520.   WARNING: This function assumes MouseDef points to 14 bytes.
  1521.  
  1522.   Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..
  1523.     bit 0 represents pixel 7 in each "MouseDef" byte.
  1524.  
  1525.   x_show_mouse
  1526.   ------------
  1527.  
  1528.   C Prototype:  void x_show_mouse()
  1529.  
  1530.   Makes the cursor visible if it was previously hidden.
  1531.   See Also: "x_hide_mouse".
  1532.  
  1533.   x_hide_mouse
  1534.   ------------
  1535.  
  1536.   C Prototype:  void x_hide_mouse()
  1537.  
  1538.   Makes the cursor hidden if it was previously visible.
  1539.   See Also: "x_show_mouse".
  1540.  
  1541.   x_mouse_remove
  1542.   --------------
  1543.  
  1544.   C Prototype:  void x_mouse_remove()
  1545.  
  1546.   Stop mouse event handling and remove the mouse handler.
  1547.  
  1548.   NOTE: This function MUST be called before quitting the program if
  1549.        a mouse handler has been installed
  1550.  
  1551.   x_position_mouse
  1552.   ----------------
  1553.  
  1554.   C Prototype  void x_position_mouse(int x, int y)
  1555.  
  1556.   Positions the mouse cursor at the specified location
  1557.  
  1558.   x_mouse_window
  1559.   ------------
  1560.  
  1561.   C Prototype:  void x_mouse_window(int x0, int y0, int x1, int y1)
  1562.  
  1563.   Defines a mouse window.
  1564.  
  1565.   x_update_mouse
  1566.   --------------
  1567.  
  1568.   C Prototype:  void x_update_mouse()
  1569.  
  1570.   Forces the mouse position to be updated and cursor to be redrawn.
  1571.   Note: this function is useful when you have set "MouseFrozen" to true.
  1572.   Allows the cursor position to be updated manually rather than
  1573.   automatically by the installed handler.
  1574.  
  1575.  
  1576. --------------------------------------------------------------------------
  1577. MODULE XBMTOOLS
  1578. --------------------------------------------------------------------------
  1579.  
  1580.   This module implements a set of functions to convert between planar
  1581.   bitmaps and linear bitmaps.
  1582.  
  1583.   PLANAR BITMAPS
  1584.  
  1585.   Planar bitmaps as used by these functions have the following structure:
  1586.  
  1587.   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  1588.   BYTE 1                 The bitmap height in rows range 1..255
  1589.   BYTE 2..n1             The plane 0 pixels width*height bytes
  1590.   BYTE n1..n2            The plane 1 pixels width*height bytes
  1591.   BYTE n2..n3            The plane 2 pixels width*height bytes
  1592.   BYTE n3..n4            The plane 3 pixels width*height bytes
  1593.  
  1594.   as used by x_put_pbm, x_get_pbm, x_put_masked_pbm.
  1595.  
  1596.   LINEAR BITMAPS
  1597.  
  1598.   Linear bitmaps have the following structure:
  1599.  
  1600.   BYTE 0                 The bitmap width in pixels  range 1..255
  1601.   BYTE 1                 The bitmap height in rows   range 1..255
  1602.   BYTE 2..n              The width*height bytes of the bitmap
  1603.  
  1604.   ASM SOURCES
  1605.  
  1606.     xbmtools.asm xpbmtools.inc model.inc
  1607.  
  1608.   C HEADER FILE
  1609.  
  1610.     xbmtools.h
  1611.  
  1612.   MACROS
  1613.  
  1614.     BM_WIDTH_ERROR
  1615.  
  1616.     LBMHeight(lbitmap)         - Height of linear bitmap "lbitmap"
  1617.     LBMWidth(lbitmap)          - Width of linear bitmap  "lbitmap"
  1618.     PBMHeight(pbitmap)         - Height of planar bitmap "pbitmap"
  1619.     PBMWidth(pbitmap)          - Width of planar bitmap "pbitmap"
  1620.  
  1621.     LBMPutPix(x,y,lbitmap,color)  - set pixel (x,y) colour in linear bitmap
  1622.     LBMGetPix(x,y,lbitmap)        - colour of pixel (x,y) in linear bitmap
  1623.  
  1624.   EXPORT FUNCTIONS
  1625.  
  1626.   x_pbm_to_bm
  1627.   ------------
  1628.   C Prototype:  extern int x_pbm_to_bm(char far * source_pbm,
  1629.                        char far * dest_bm);
  1630.  
  1631.   This function converts a bitmap in the planar format to the linear format
  1632.   as used by x_compile_bitmap.
  1633.  
  1634.   WARNING: the source and destination bitmaps must be pre - allocated
  1635.  
  1636.   NOTE: This function can only convert planar bitmaps that are suitable.
  1637.     If the source planar bitmap's width (per plane) is >= 256/4
  1638.     it cannot be converted. In this situation an error code
  1639.     BM_WIDTH_ERROR. On successful conversion 0 is returned.
  1640.  
  1641.   x_bm_to_pbm
  1642.   ------------
  1643.   C Prototype:  extern int x_bm_to_pbm(char far * source_pbm,
  1644.                        char far * dest_bm);
  1645.  
  1646.   This function converts a bitmap in the linear format as used by
  1647.   x_compile_bitmap to the planar formap.
  1648.  
  1649.   WARNING: the source and destination bitmaps must be pre - allocated
  1650.  
  1651.   NOTE: This function can only convert linear bitmaps that are suitable.
  1652.     If the source linear bitmap's width is not a multiple of 4
  1653.     it cannot be converted. In this situation an error code
  1654.     BM_WIDTH_ERROR. On successful conversion 0 is returned.
  1655.  
  1656.